home *** CD-ROM | disk | FTP | other *** search
/ Amiga Plus Special 25 / AMIGAplus Sonderheft 25 (2000)(Falke)(DE)(Track 1 of 4)[!].iso / Updates / HD-Installer / -WHDLoad- / WHDLoad_dev / Autodoc / whdload.doc
Text File  |  2000-05-08  |  47KB  |  1,278 lines
  1. TABLE OF CONTENTS
  2.  
  3. WHDLoad/--Overview--
  4. WHDLoad/resload_Abort
  5. WHDLoad/resload_Control
  6. WHDLoad/WHDLTAG_CBSWITCH_SET
  7. WHDLoad/resload_CRC16
  8. WHDLoad/resload_Decrunch
  9. WHDLoad/resload_DiskLoad
  10. WHDLoad/resload_DiskLoadDev
  11. WHDLoad/resload_FlushCache
  12. WHDLoad/resload_GetFileSize
  13. WHDLoad/resload_ListFiles
  14. WHDLoad/resload_LoadFile
  15. WHDLoad/resload_LoadFileDecrunch
  16. WHDLoad/resload_LoadFileOffset
  17. WHDLoad/resload_ProtectRead
  18. WHDLoad/resload_ProtectReadWrite
  19. WHDLoad/resload_ProtectRemove
  20. WHDLoad/resload_ProtectWrite
  21. WHDLoad/resload_SaveFile
  22. WHDLoad/resload_SaveFileOffset
  23. WHDLoad/resload_SetCACR
  24. WHDLoad.Slave/--Overview--
  25.  
  26. WHDLoad/--Overview--
  27.  
  28. The calling conventions for all functions are similar to the OS-Library-
  29. concept. Parameters are provided in registers (except "resload_Abort"),
  30. return codes comes in D0 (on some functions also in D1). After a function call
  31. the registers D0-D1/A0-A1 are destroyed (D0,D1 may contain a returncode) they
  32. are so called scratch registers. All other registers are preserved.
  33. The base of the JMP tower in WHDLoad is similar to a LibraryBase. In 
  34. difference to the OS the base must not stand in A6 on calling a function, but
  35. it is recommend to call all functions relative to a address register like
  36.         move.l  (_resload,pc),a5
  37.         JMP     (resload_Decrunch,a5)
  38. The resload base is overgiven in A0 on calling the Slave first via 
  39. ws_GameLoader (see chapter WHDLoad.Slave/--Overview--).
  40.  
  41.  
  42. explanation of some keywords used in this document:
  43.  
  44. Slave           the file which contains the interface code
  45.                 (see chapter WHDLoad.Slave/--Overview--)
  46.  
  47. DiskImage       a Floppy-disk stored as a file on Harddisk
  48.  
  49. BaseMem         the size of the memory used by the installed program
  50.                 this value is specified in the Slave : ws_BaseMemSize
  51.                 this is also the upper bound of chip-mem for the installed
  52.                 program
  53.  
  54. logical values used for returncodes (see dos/dos.i):
  55.  
  56. TRUE = -1 (or better <>0)
  57. FALSE = 0
  58.  
  59. WHDLoad/resload_Abort
  60.  
  61.    NAME
  62.         resload_Abort -- quit and return to operating system
  63.         
  64.    SYNOPSIS
  65.         resload_Abort( success, primary, secondary)
  66.                          (a7)    (4,a7)    (8,a7)
  67.                         ULONG    ULONG     ULONG
  68.  
  69.    FUNCTION
  70.         terminates the program and return to OS
  71.  
  72.    INPUTS
  73.         success -   the reason for terminating
  74.                     one of TDREASON_#? ,defined in "whdload.i"
  75.                     depending on this value WHDLoad will continue different
  76.                 TDREASON_OK
  77.                     a normal exit will performed
  78.                 TDREASON_DEBUG
  79.                     WHDLoad will make a memory dump to .whdl_memory and a
  80.                     register dump to .whdl_register after this it will exit
  81.                 TDREASON_#? (except the above)
  82.                     WHDLoad will show an requester which displays the reason
  83.                     of failure, the user can now choose between "Quit",
  84.                     "Restart" and "Make CoreDump"
  85.         primary -   the primary errorcode, depends on success/TDREASON_#?
  86.                     TDREASON_DOSREAD,TDREASON_DOSWRITE,TDREASON_DOSLIST,
  87.                     TDREASON_DISKLOAD,TDREASON_DISKLOADDEV
  88.                       --> dos-errorcode/trackdisk-errorcode
  89.                     TDREASON_DEBUG
  90.                       --> program counter (to write it to the register dump)
  91.         secondary - the secondary errorcode, depends on success/TDREASON_#?
  92.                     TDREASON_DOSREAD,TDREASON_DOSWRITE,TDREASON_DOSLIST
  93.                       --> pointer to filename
  94.                     TDREASON_DISKLOAD
  95.                       --> disk number
  96.                     TDREASON_DEBUG
  97.                       --> status register (to write it to the register dump)
  98.  
  99.    EXAMPLE
  100.         to simply quit:
  101.                 ;primary and secondary wont be needed
  102.                 move.l  #TDREASON_OK,-(a7)
  103.                 move.l  (_resload,pc),a0
  104.                 jmp     (resload_Abort,a0)
  105.         to quit because reading of a file has failed:
  106.                 move.l  a0,-(a7)                        ;a0 = filename
  107.                 move.l  d0,-(a7)                        ;d0 = doserror code
  108.                 move.l  #TDREASON_DOSREAD,-(a7)
  109.                 move.l  (_resload,pc),-(a7)
  110.                 add.l   #resload_Abort,(a7)
  111.                 rts
  112.  
  113.    RESULT
  114.         nothing because WHDLoad will never return from this call
  115.  
  116.    BUGS
  117.  
  118.    NOTE
  119.         this routine is the only which must called via JMP and not JSR,
  120.         because the parameters lies on the stack
  121.         (this has the advantage that if success==TDREASON_DEBUG the registers
  122.         can preserved)
  123.  
  124.    SEE ALSO
  125.         example slaves
  126.  
  127. WHDLoad/resload_Control
  128.  
  129.    NAME
  130.         resload_Control
  131.         
  132.    SYNOPSIS
  133.         success = resload_Control(taglist)
  134.           D0                        A0
  135.          BOOL                      APTR
  136.  
  137.    FUNCTION
  138.         control function of WHDLoad, get variables from WHDLoad,
  139.         set variables in WHDLoad depending on the tags in the overgiven
  140.         taglist
  141.  
  142.    INPUTS
  143.         taglist - pointer to a table of tagitems
  144.         
  145.         WHDLTAG_ATTNFLAGS_GET  - gets the AttnFlags from systems execbase
  146.         WHDLTAG_ECLOCKFREQ_GET - gets the EClockFrequency from systems
  147.                                  execbase
  148.         WHDLTAG_MONITOR_GET    - gets the used monitor, the value will be
  149.                                  eiter NTSC_MONITOR_ID or PAL_MONITOR_ID
  150.                                  (defined in graphics/modeid.i), the used
  151.                                  monitor depends on execbase.VBlankFrequency
  152.                                  and can set by the user via tooltypes
  153.                                  NTSC and PAL
  154.         WHDLTAG_BUTTONWAIT_GET - returns -1 if argument/tooltype ButtonWait
  155.                                  is set, otherwise returns 0
  156.         WHDLTAG_CUSTOM1_GET
  157.         WHDLTAG_CUSTOM2_GET
  158.         WHDLTAG_CUSTOM3_GET
  159.         WHDLTAG_CUSTOM4_GET
  160.         WHDLTAG_CUSTOM5_GET    - returns numerical value of argument/tooltype
  161.                                  Custom1 .. Custom5
  162.         WHDLTAG_CBSWITCH_SET   - sets callback function to execute on switch
  163.                                  to installed program
  164.  
  165.    EXAMPLE
  166.                 ...
  167.                 clr.l   -(a7)                           ;TAG_DONE
  168.                 clr.l   -(a7)                           ;data to fill
  169.                 move.l  #WHDLTAG_ATTNFLAGS_GET,-(a7)
  170.                 move.l  a7,a0
  171.                 move.l  (_resload,pc),a2
  172.                 jsr     (resload_Control,a2)
  173.                 move.w  (6,a7),d0                       ;D0 = AttnFlags
  174.                 lea     (12,a7),a7                      ;restore sp
  175.                 ...
  176.                 
  177.    EXAMPLE
  178.                 ...
  179.                 lea     (_tags,pc),a0
  180.                 move.l  (_resload,pc),a2
  181.                 jsr     (resload_Control,a2)
  182.                 move.w  (_attn,pc),d0                   ;D0 = AttnFlags
  183.                 ...
  184.         _tags
  185.                 dc.l    WHDLTAG_MONITOR_GET
  186.         _mon    dc.l    0
  187.                 dc.l    WHDLTAG_ATTNFLAGS_GET
  188.                 dc.w    0                               ;padding
  189.         _attn   dc.w    0
  190.                 dc.l    0                               ;TAG_DONE
  191.  
  192.    RESULT
  193.         success is true if all tags in the taglist are correctly processed
  194.         GET items in the taglist are filled with the requested data
  195.  
  196.    BUGS
  197.  
  198.    NOTE
  199.         requires ws_Version >= 5
  200.  
  201.    SEE ALSO
  202.  
  203. WHDLoad/WHDLTAG_CBSWITCH_SET
  204.  
  205.    NAME
  206.         WHDLTAG_CBSWITCH_SET
  207.         
  208.    SYNOPSIS
  209.         to be used with resload_Control
  210.  
  211.    FUNCTION
  212.         with this tag a function can be set which will executed from WHDLoad
  213.         when it switches from the OS to the installed program, the aim is to
  214.         give a possebilty to fix the problem that some Custom registers are 
  215.         destroyed during such a switch
  216.         at the time this routine will be executed all interrupts and dma's are
  217.         disabled and the installed programs memory is restored
  218.         the function MUST not change any register, MUST not use stack and MUST
  219.         return via "JMP (A0)"
  220.         known r